Current approach

This PR is an attempt to resolve #21061 by using Doxygen aliases. Developer can add a list of function properties by using @funcprops \prop1, ..., \propN. They will be rendered as plain text in the Doxygen build and a with a link to terminology on the Sphinx side. Note that this solution does not allow to obtain a list of, e.g. "all functions that are async".

Doxygen output:

Sphinx output:

Pros: Minimal changes, standardized keywords, renders links on the Sphinx side
Cons: Plain-text on the Doxygen side, not possible to list functions with a certain property

Other options

Links to terminology in both Doxygen and Sphinx

In order to achieve this functionality the terminology.rst content needs to be moved to a Doxygen page. Then, the ALIAS can contain, e.g. @ref async. The content of the Doxygen page can be rendered back in Sphinx using the recently added ..doxygenpage directive in breathe, together with breathe-doc/breathe#645.

Doxygen output:

Sphinx output:

Pros: Function properties contain link to terminology in both, Doxygen and Sphinx.
Cons: Terminology has to be moved to Doxygen

List of functions with a certain property

In order to obtain a list of functions that have a certain property, e.g. async I have tried the options listed below. Note that I haven't had success in obtaining a fully functional solution.

\xrefitem

Using \xrefitem <key> "(heading)" "(list title)" { text } a new page is created in the Doxygen side with a list of all functions that have the property set. One of the problems is that the generated page is added to the root of the Doxygen tree. Furthermore, I haven't been able to make this option work reliably when multiple properties are used.

Doxygen:

Sphinx:

Pros: Pages with a list of all functions with a certain property are generated
Cons: Not working properly on the Sphinx side (renders empty), page location can't be controlled in the Doxygen side

\ingroup

The advantage of using groups is that pages location can be controlled (e.g. creating a parent group somewhere in the hierarchy). However, the function will be listed in only one group, so it is not an option.

From Doxygen documentation:

Note that compound entities (like classes, files and namespaces) can be put into multiple groups, but members (like variable, functions, typedefs and enums) can only be a member of one group (this restriction is in place to avoid ambiguous linking targets in case a member is not documented in the context of its class, namespace or file, but only visible as part of a group).

Pros: None
Cons: Does not work when multiple properties are used.

Table of properties

In order to generate something like:

I haven't found a solution using existing Doxygen/Sphinx/Breathe facilities. On the Doxygen side we should have conditionals to evaluate certain properties of a function. As fas as I know, this is not possible. Onthe Sphinx side we need to implement a new custom plugin that parses Doxygen XML files and generates such table. It may be possible to re-use breathe parser, but I'm not sure it it is worth for this purpose due to its "complexity".